Skip to main content
Version: 5.2.0.0

Orchestra Upgrade Guide

A migration of Orchestra should be performed with minimal downtime in production. To achieve this, effective planning, detailed testing, and a strict migration plan are necessary.

Patch Manager

If you are planning to apply a patch, it is recommended to use the Patch Manager to apply a patch to your Orchestra installation. This allows you to apply the patch to your upgraded Orchestra installation with minimal application of manual changes.

Pre-Upgrade Steps​

Planning the Downtime​

  1. Identify stakeholders and technical administrators of systems connected to Orchestra.

  2. Schedule downtime for the Orchestra server with technical administrators.

  3. Ensure that technical administrators are available during the migration process.

  4. Announce the downtime to stakeholders and technical administrators.

  5. If necessary, obtain a declaration of consent from stakeholders.

Download the Orchestra Release to be Installed​

  1. Download the Orchestra Release zip file:

    • Either from the Customer Portal (if you purchased Orchestra from Soffico GmbH).
    • Or from your Orchestra provider (if you purchased the Orchestra license in a software bundle).

    Unpack the downloaded zip file into a directory. The zip file contains the subdirectories Application, Database, Manual, Startscripts, and Third Party Libraries.

  2. Review the release notes for changes compared to the previous version. You can retrieve the release notes either from the Customer Portal download section or by inquiring with your purchaser.

  3. Document any changes to be made to the Orchestra server and your interfaces during the upgrade.

Upgrade All Scenarios to the New Orchestra Version​

  1. Open the scenarios currently running your Orchestra instance in the new Orchestra Designer and validate them.

  2. If necessary, adapt the scenarios to the new Orchestra release. Upon opening, a pop-up will prompt you to confirm that you want to migrate the scenarios to the new Orchestra version.

    warning

    This change cannot be undone!

  3. Document all modifications made.

  4. Export the upgraded scenarios as .psc files to your local machine.

Configure the New Orchestra​

Licensing​

To ensure a valid license after the upgrade, one of the following steps must be performed:

  • Move the licensestore (Application/orchestra/WEB-INF/licensestore) from the existing Orchestra version to the new version.

  • Import all license files into the monitor again.

Otherwise, the licenses will be corrupted.

environment_settings.xml​

The environment_settings.xml of the new Orchestra version may not be identical to your current environment. Therefore, take values from the old environment_settings.xml and modify the new environment_settings.xml to fit your local Orchestra environment. Settings that usually require modification include database connections, long-term archive, and possibly cluster configuration.

The code snippet below shows the database group within the environment_settings.xml that contains the database connection settings.

Please provide:

  • Type of your database. You can choose values from MYSQL, ORACLE, POSTGRESQL, MSSQL, MARIADB, or Derby depending on your database type.

  • Your database's URL, which can be copied from the old environment_settings.xml file.

  • The encrypted database username. The plaintext username is encrypted using the Password Manager Tool.

  • The encrypted database password. The plaintext password is encrypted using the Password Manager Tool.

You can find these tools within the Orchestra zip file:

  • Linux: Startscripts/Unix/pwd_manager.sh

  • Windows: Startscripts/Windows/pwd_manager.cmd

note

Before the Password Manager tools can be used, it might be necessary to adapt some configurations in the file orchestra_env.bat (Windows) / orchestra_env.sh (Unix). These files are located in the same directory as the tools. Simply change the value of the ORC_JAVA_HOME variable to match the location of your Java JDK/JRE:

  • Windows:

    set ORC_JAVA_HOME=%JAVA_HOME%

  • Unix:

    ORC_JAVA_HOME=$JAVA_HOME
<group name="database" enabled="true">
  <parameter name="runtime.db.typ" value="MYSQL" choice="MSSQL|MYSQL|ORACLE|POSTGRESQL|MARIADB|Derby"/>
  <parameter name="runtime.url" value="jdbc:mysql://127.0.0.1:3306/ORC"/>
  <parameter name="runtime.user" value ="0008504c5346494d54530006626c6a706d640000001011cc4aa782f20289643347ab43dff35e" />
  <parameter name="runtime.pwd" value ="0008504c5346494d54530006626c6a706d640000001011cc4aa782f20289643347ab43dff35e" />
</group>

environment_settings_template.xml (Optional)​

The environment_settings_template.xml is used for the initial setup of the Orchestra Runtime. It contains default port configurations, timeouts, housekeeping configurations, etc. All entries from your old Orchestra installation are already stored in the Orchestra Runtime database.

You can find this file here: ../Orchestra/WEB-INF/classes/config/environment_settings_template.xml.

If NEW parameters (like new port numbers) that do not yet exist in the database are loaded from the NEW environment_settings_template.xml on first startup, they may be modified later via the Orchestra monitor.

Since some of these settings require a restart of the Orchestra runtime, it is recommended to check for new parameter groups or changes in parameter groups and adjust them to fit your environment to prevent the need for another restart of the Orchestra runtime.

Backup of Orchestra Folder from Apache Tomcat's ../webapp​

It is advisable to perform a full snapshot of the entire Orchestra directory containing the old Orchestra installation.

Backup the Production Database​

Create and save a dump of your Orchestra database.

MySQL​

mysqldump --opt -Q -u username -p password -h DB_Host ORC > "C:\Users\temp dumpOrc.sql"

Oracle​

For information on backing up/restoring your Oracle Release 12.2.0.1-ee database, refer to the official Oracle Tutorial: Oracle Backup and Recovery Tutorial.

MSSQL​

Backup with SQL Server Management Studio (SSMS)​

Start the SQL Server Import and Export Wizard from SQL Server Management Studio (SSMS). In SQL Server Management Studio, connect to an instance of the SQL Server Database Engine.

Expand Databases, right-click a database, point to Tasks, and click one of the following options:

  • Import Data
  • Export Data
Backup with the SQL Server Import and Export Wizard​

Start the SQL Server Import and Export Wizard from the Windows Start menu.

  1. On the Start menu, find and expand Microsoft SQL Server.
  2. Click one of the following options:
    • SQL Server Import and Export Data (64-bit)
    • SQL Server Import and Export Data (32-bit)

Run the 64-bit version of the wizard unless you are certain that your data source requires a 32-bit data provider.

Save Database Files from Server Installation​

Start the file explorer from the Start menu.

  1. Navigate to your Microsoft SQL Server Data Store.
  2. Save the ORCHESTRA.mdf and ORCHESTRA_log.ldf files.

For further information regarding backup/restoration of your MSSQL database: Copy Databases with Backup and Restore.

Shutdown Orchestra​

  • Disable all inbound triggers (signals, timers, channels, web services) in the Orchestra Monitor.
  • Check for any ongoing processes (see description below). There must not be any running, paused, or warning processes.
  • Finally, stop Apache Tomcat.

Check Whether All Processes Are Finished and Signals Are Processed from within the Database​

To ensure that all processes have been successfully completed, please check the following tables. None of the SELECT statements should return any values. If results are returned, this indicates that unfinished processes still exist.

  • Check running processes in orc_process_state. The numbers in the following statement have the meaning RUNNING = 18, WARNING = 10, PAUSED = 2:

    SELECT * FROM orc_process_state WHERE prs_state IN (18,10,2);

  • Check running processes in orc_process_runtime_state (RUNNING = 0, CANDIDAT_FOR_RESTART = 4, MARK_FOR_RESTART = 3, SCHEDULED_FOR_RESTART = 4):

    SELECT * FROM orc_process_runtime_state WHERE prs_state IN (0,2,3,4);

  • Check running processes in orc_processinstance_state (if there are entries here, there are still persistent processes):

    SELECT count (*) FROM orc_processinstance_state;

  • Check table orc_work_queue:

    SELECT count (*) FROM orc_work_queue;

The column CREATDAT can be used to determine how old an entry is. If entries are older than 1 hour, delete them. Entries with the status -1 and -9 can also be deleted via SQL.

  • Check table orc_topic_queue:

    SELECT count (*) FROM orc_topic_queue WHERE state <> - 9;

Upgrade the Database Instance​

Upgrade the Database by Using SQL Scripts​

Log in to the database as the database admin user. Run all upgrade scripts from within the Database directory. All scripts contain a version tag in their file names. Select all scripts with a version tag greater than your current Orchestra version. For example, if your current Orchestra version is 4.6.1.0, execute all scripts from version 4.6.2.0 onwards.

The xx_orchestra_partner.sql script only needs to be executed when working with partner management, which is not required in most installations.

Flyway is a simple but powerful tool that helps to maintain your database properly. Key reasons to use Flyway include:

  • Database schema versioning.
  • Consistent database migration.
  • Easy maintenance of the database.

Flyway has a command line tool that provides commands such as:

  • migrate
  • clean
  • info
  • validate
  • baseline
  • repair

Flyway maintains a dedicated table called flyway_schema_history to perform its tasks. This table exists alongside other tables in Orchestra.

For more details, refer to https://flywaydb.org.

warning

Flyway is only usable for databases that have been created with Flyway from scratch. You cannot migrate existing databases created with SQL scripts or any other tools.

Orchestra Database Migration​

Please remember that you need to manually create your user in the DB. With Flyway, we do not maintain system scripts as in MySQL, MSSQL, Oracle, PostgreSQL, or MariaDB, but rather handle schema and, optionally, a small dataset (e.g., adding an admin user).

For migrating and maintaining the Orchestra database, we have the following options:

Configuring Flyway​

The following steps prepare Flyway for use:

  • Edit the configuration file conf/flyway.toml.example, setting the correct database connection string, script locations, and optionally other parameters (more details here: https://flywaydb.org/documentation/commandline/migrate).

  • SQL scripts are located in the sql directory by default. The script location can be specified in flyway.toml.example. A sample flyway.toml.example is shown below:

    url=jdbc:mysql://localhost:3306/orctrunk
    user=ORCTRUNK
    password=ORCTRUNK
    locations=filesystem:sql/mysql
    • url: URL of the database to be used.
    • user: User used to connect to the database.
    • password: Password used to connect to the database.
    • location: Relative path to the directory containing the SQL scripts used for migration.

  • JDBC Driver: Your JDBC driver is located in the drivers directory.

Here is a representation of a typical Flyway directory containing files and subdirectories:

Migrate​

Migration is performed using the command line tool:

flyway migrate

All SQL scripts with a version number greater than the current version of your DB schema (from the table flyway_schema_history) will be executed.

Baseline and Migrate​

To use this option, first determine the current version of your Orchestra DB, i.e., the Orchestra Release you are using. Having identified this version (e.g., V4.5.5.0), find the matching script version of the SQL script(s) (for the example, this would be V75__V4.5.5.0_upgrade.sql). You can then establish the baseline for your database schema:

flyway -baselineVersion=75 -baselineDescription="Base version up to orchestra V4.5.5.0" baseline

This command will create a table flyway_schema_history and store the baseline version within it. After setting the baseline, the migration is also executed with:

flyway migrate

All SQL scripts with a version number greater than the baseline version of your database schema will be executed.

warning

Setting the baseline version and subsequently migrating via Flyway should only be used on an existing Orchestra without Partner Management and no Orchestra cluster.

danger

Do NOT run flyway clean - this command will remove your entire Orchestra runtime schema from the database!

Flyway Migration with a Version Below 4.12​

The checksum error for installations prior to version 4.10 can be resolved using the command flyway repair.

note

Previously, the Flyway table name was 'schema_version', while now it is called 'flyway_schema_history'. Renaming the table should also resolve any remaining issues.

Without Flyway​

Please refer to MySQL, MSSQL, Oracle, PostgreSQL, or MariaDB.

Upgrade the Orchestra Runtime​

Tomcat​

Manually Replacing the Orchestra Directory in Tomcat​

Replace the ./webapps/orchestra directory in the Tomcat directory with the folder orchestra from within your Orchestra CD's Application directory. Before restarting Tomcat, check the classpath.

For additional information, see Tomcat (Windows), Tomcat (Linux), and the Password Manager Tool.

Deploy as WAR File​

After configuring your new Orchestra instance, zip the contents of the orchestra directory. The resulting .zip file must contain the directories lib_designer, libext, orchestra_web, and WEB-INF at the root level. If these directories are not at the root level, the deployment will fail. Rename this file to orchestra.war. You can then deploy the created WAR file via the Tomcat Manager Web GUI as a Web app (WAR file to deploy) or simply copy it into the Tomcat's webapps directory.

For additional information, see Tomcat (Windows) or Tomcat (Linux).

Start the New Orchestra Version​

Start Tomcat and check if the Orchestra web app has started successfully. To do so, try to access the Orchestra monitor at http://<your-tomcat-url>/Orchestra or via the Tomcat Web Application Manager GUI.

  • Check the log files for any errors to ensure no issues occurred during the startup of your Orchestra installation. If no log files are created, verify that the directory exists and that the user has permission to write to the log directory. Further information may be found in Tomcat's catalina.logs.

  • In the case of a cluster installation, verify that all cluster connections are functioning properly.

  • If you have a setup with Juno instances, ensure that the Juno instances are connected.

  • Activate all inbound triggers.

  • Check if processes are starting correctly.

  • Announce the completion of the Orchestra upgrade to all stakeholders and technical administrators.

WebLogic​

Stop and Delete the Deployment​

On the WebLogic Server, the deployed WAR file (Orchestra runtime) must be stopped and completely deleted. Redeployment is insufficient. To remove the old Orchestra instance from the WebLogic server, follow these steps:

  • Log in to the WebLogic Admin Console and navigate to Domain Structure -> Deployments.

  • In the Control tab, select orchestra and click Stop.

  • Then select Lock and Edit.

  • In the Control tab, select orchestra and click on Delete.

  • After that, click Accept Changes.

Restart the WebLogic Server​

Currently, the WebLogic server on which the orchestra.war was deployed must also be stopped after removing the Orchestra Runtime. Otherwise, the libraries will not be retrieved correctly from the WebLogic server during the new deployment.

Upgrade Human Interaction​

To upgrade Human Interaction with a new version, ensure that the worklist-ui.jar file has the same version number as your new Orchestra. For setup instructions, please refer to the corresponding chapter in the Designer Manual.